Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

NS_DEV_DOCFOR:objc_class:Box;,Box

Inherits From:	View : Responder : Object

Declared In:	appkit/Box.h

Class Description

A Box object is a simple View that can do two things:  It can draw a border around itself and it can title itself.  You use a Box to group, visually, some number of other Views.  These other Views are added to the Box through the typical subview-adding methods, such as addSubview: and replaceSubview:with:.  

A Box contains a content area, a rectangle set within the Box's frame in which the Box's subviews are displayed.  The size and location of the content area depends on the Box's border type, title location, the size of the font used to draw the title, and an additional measure that you can set through the setOffsets:: method.  When you create a Box, a instance of View is created and added (as a subview of the Box object) to fill the Box's content area.  If you replace this content view with a View of your own, your View will be resized to fit the content area.  Similarly, as you resize a Box its content view is automatically resized to fill the content area.  

The Views that you add as subviews to a Box are actually added to the Box's content viewÐView's subview-adding methods are redefined by Box to ensure that a subview is correctly placed in the view hierarchy.  However, you should note that the subviews method isn't redefined:  It returns a List containing a single object, the Box's content view.

Instance Variables

id cell;

id contentView;

NXSize offsets;

NXRect borderRect;

NXRect titleRect;

struct _bFlags {
	unsigned int borderType:2;
	unsigned int titlePosition:3;
} bFlags;

cell 	The cell that draws the Box's title.

contentView 	The Views that fills the Box's content area.

offsets 	Offsets of the content view from the Box's border.

borderRect 	The Box's border rectangle.

titleRect 	The rectangle in which the title cell is drawn.

bFlags.borderType	A constant describing the Box's border type.

bFlags.titlePosition	A constant describing the position of the Box's title.

Method Types

Initializing and freeing 	- initFrame:
- free

Setting the border and title	- setBorderType: 
- borderType
- setTitlePosition:
- titlePosition
- setTitle: 
- title
- setFont: 
- font
- cell

Setting and placing the content view
- setContentView:
- contentView
- setOffsets::
- getOffsets: 

Putting Views in the Box	- addSubview: 
- replaceSubview:with:

Resizing the Box	- setFrameFromContentFrame: 
- sizeTo::
- sizeToFit

Drawing the Box	- drawSelf::

Archiving	- awake
- read:
- write:

Instance Methods

NS_DEV_DOCFOR:objc_method:[Box-addSubview:];,addSubview:

- addSubview:aView

Adds aView to the Box.  This is done by forwarding the addSubview:aView message to the Box's content view.  Note that this means aView's location and size are reckoned within the content view's coordinate system. After invoking this method, you should send the Box a sizeToFit message.  Returns self.

NS_DEV_DOCFOR:objc_method:[Box-awake];,awake

- awake

Lays out the Box during the unarchiving process so that it can be displayed.  You should never invoke this method directly.

NS_DEV_DOCFOR:objc_method:[Box-borderType];,borderType

- (int)borderType

Returns the Box's border type, one of NX_LINE, NX_GROOVE, NX_BEZEL, or NX_NOBORDER.  By default, a Box's border type is NX_GROOVE.

See also:  - setBorderType:

NS_DEV_DOCFOR:objc_method:[Box-cell];,cell

- cell

Returns the cell used to display the Box's title.

NS_DEV_DOCFOR:objc_method:[Box-contentView];,contentView

- contentView

Returns the Box's content view.  The content view is created automatically when the Box is created, and resized as the Box is resized (you should never send frame-altering messages directly to a Box's content view).  You can replace it with a View of your own through the setContentView: method.

See also:  - setContentView:

NS_DEV_DOCFOR:objc_method:[Box-drawSelf::];,drawSelf::

- drawSelf:(const NXRect *)rects :(int)rectCount

Fills the Box's background with opaque, light gray (NX_LTGRAY) paint, then draws the object's title, border, and its subviews (you can't change the background color short of creating your own Box subclass).  You never invoke this method directly; it's invoked by the display methods inherited from the View class.  Returns self.

NS_DEV_DOCFOR:objc_method:[Box-font];,font

- font

Returns the Font object used to draw the Box's title.  By default, the Font is the 12.0 point system font (NXSystemFont).

See also:  - setFont:

NS_DEV_DOCFOR:objc_method:[Box-free];,free

- free

Frees the Box and all its subviews.

NS_DEV_DOCFOR:objc_method:[Box-getOffsets:];,getOffsets:

- getOffsets:(NXSize *)theSize

Returns, by reference in theSize, the horizontal and vertical distances between the Box's border and its content area, measured in the Box's coordinate system.  The default is 5.0 in both dimensions.  Returns self.

See also:  - setOffsets::

NS_DEV_DOCFOR:objc_method:[Box-initFrame:];,initFrame:

- initFrame:(const NXRect *)frameRect

The designated initializer for the Box class, this method initializes the Box with the following values:

Attribute	Value

frame	frameRect
title	ªTitleº
border type	NX_RIDGE
title position	NX_ATTOP
font	12.0 point NXSystemFont 
offsets	5.0 in both dimensions

In addition, the Box's content view is automatically created and added as the Box's single subview, and the Box identifies itself as an opaque View.  Returns self.

NS_DEV_DOCFOR:objc_method:[Box-read:];,read:

- read:(NXTypedStream *)stream

Reads the Box from the typed stream stream.  Returns self.

See also:  - write:

NS_DEV_DOCFOR:objc_method:[Box-replaceSubview:with:];,replaceSubview:with:

- replaceSubview:oldView with:newView

Replace oldView with newView in the subview list of the Box's content view.  This method does nothing and returns nil if oldView isn't a subview of the content view or if newView isn't a View.  Otherwise, this method returns oldView.

See also:  - addSubview:

NS_DEV_DOCFOR:objc_method:[Box-setBorderType:];,setBorderType:

- setBorderType:(int)aType

Sets the border type to aType, which must be NX_LINE, NX_GROOVE, NX_BEZEL, or NX_NOBORDER (a Box's default border type is NX_GROOVE).  If the size of the new border is different from that of the old border, the content view is resized to absorb the difference.  The Box isn't redisplayed.  Returns self.

See also:  - borderType

NS_DEV_DOCFOR:objc_method:[Box-setContentView:];,setContentView:

- setContentView:aView

Sets the Box's content view to aView, resizing the View to fit within the Box's current content area.  The old content view is returned.

See also:  - contentView

NS_DEV_DOCFOR:objc_method:[Box-setFont:];,setFont:

- setFont:fontObj

Sets fontObj as the Font object used to draw the Box's title.  By default, the title is drawn using the 12.0 point system font (NXSystemFont).  If the size of the new Font is different from that of the old Font, the content view is resized to absorb the difference.  The Box isn't redisplayed.  Returns self.

See also:  + newFont:size: (Font)

NS_DEV_DOCFOR:objc_method:[Box-setFrameFromContentFrame:];,setFrameFromContentFrame:

- setFrameFromContentFrame:(const NXRect *)contentFrame

Places the Box so its content view lies on contentFrame, reckoned in the coordinate system of the Box's superview.  Returns self.

See also:  - setOffsets::, - setFrame: (View)

NS_DEV_DOCFOR:objc_method:[Box-setOffsets::];,setOffsets::

- setOffsets:(NXCoord)horizontal :(NXCoord)vertical

Sets the horizontal and vertical distance between the border of the Box and its content view.  The horizontal value is applied (reckoned in the Box's coordinate system) fully and equally to the left and right sides of the Box.  The vertical value is similarly applied to the top and bottom.  Returns self

Unlike changing a Box's other attributes, such as its title position or border type, changing the offsets doesn't automatically resize the content view.  In general, you should send a sizeToFit message to the Box after changing the size of its offsets.  This causes the content view to remain unchanged while the Box is wrapped around it.

NS_DEV_DOCFOR:objc_method:[Box-setTitle:];,setTitle:

- setTitle:(const char *)aString

Sets the title to aString.  By default, a Box's title is ªTitleº.  After invoking this method you should send a sizeToFit message to the Box to ensure that it's wide enough to accommodate the length of the title.  Returns self.

See also:  - title, - setFont:

NS_DEV_DOCFOR:objc_method:[Box-setTitlePosition:];,setTitlePosition:

- setTitlePosition:(int)aPosition

Sets the title position to aPosition, which can be one of the values listed in the following table.  The default position is NX_ATTOP.

Value	Meaning

NX_NOTITLE	The Box has no title
NX_ABOVETOP	Title positioned above the Box's top border
NX_ATTOP	Title positioned within the Box's top border
NX_BELOWTOP	Title positioned below the Box's top border
NX_ABOVEBOTTOM	Title positioned above the Box's bottom border
NX_ATBOTTOM	Title positioned within the Box's bottom border
NX_BELOWBOTTOM	Title positioned below the Box's bottom border

If the new title position changes the size of the Box's border area, the content view is resized to absorb the difference.  The Box isn't redisplayed.  Returns self.

See also:  - getTitlePosition:

NS_DEV_DOCFOR:objc_method:[Box-sizeTo::];,sizeTo::

- sizeTo:(NXCoord)width :(NXCoord)height

Resizes the Box to width and height.  The Box's content view is resized accordingly; if the new width or height of the Box leaves no room for the content view (after subtracting the room needed to accommodate the border, title, and offsets), the respective dimension of the content view will be zero.  Returns self.

NS_DEV_DOCFOR:objc_method:[Box-sizeToFit];,sizeToFit

- sizeToFit

Resizes and moves the Box's content view so that it just encloses its subviews.  The Box itself is then moved and resized to wrap around the content view.  The Box's width is constrained so its title will be fully displayed.  

You should invoke this method after:

·	Adding a subview (to the content view).
·	Altering the size or location of such a subview.
·	Setting the Box's offsets.
·	Setting the Box's title.

The mechanism by which the content view is moved and resized depends on whether the object responds to its own sizeToFit message:  If it does respond, then that message is sent and the content view is expected to be so modified.  If the content view doesn't respond, the Box moves and resizes the content view itself. 

Returns self.

NS_DEV_DOCFOR:objc_method:[Box-title];,title

- (const char *)title

Returns the Box's title.  By default, a Box's title is ªTitleº.

See also:  - setTitle:

NS_DEV_DOCFOR:objc_method:[Box-titlePosition];,titlePosition

- (int)titlePosition

Returns a constant representing the title position.  See the description of setTitlePosition: for a list of the title position constants.

See also:  - setTitlePosition:

NS_DEV_DOCFOR:objc_method:[Box-write:];,write:

- write:(NXTypedStream *)stream

Writes the Box to the typed stream stream.  Returns self.

See also:  - read: